Developer CD Series 1993…ch: Other People's Memory/ADC Developer CD (1993-03) (''Other People's Memory'')_iso/Dev.CD Mar 93.iso/Technical Documentation/Sample Code/DTS.Lib & Samples/=How to write your app

Text File | 1992-10-22 | 32.0 KB | 764 lines | [TEXT/MPS ]

The title of this document should have been:

How to write your application using Zippo.

The above is too long for a file name, but obviously the title I used got your
attention.  Now all I have to do is to hold it...

If you have built the libraries and sample applications, you may have already
noted that Zippo is actually an executable application.  Of course, it does
absolutely nothing useful.  That's your job.

First, let me state what you have built.  If you use MPW, you built the library
DTS.Lib.  If you are a Think user, you built the libraries DTS.Lib..framework,
DTS.Lib..strings, and DTS.Lib..utils.

Think limits a library to a single 32k segment, so the library code had to be
broken up into separate libraries for Think users.  MPW allows as big a library
as you want, so it is all in one piece.  Either way, you only link in the code
that you call, so both are efficient.

For Think C users, DTS.Lib..strings.π contains only a single source file,
StringUtils.c.  StringUtils.c contains some useful string functions.  It allows
you to do various functions that are supplied by sprintf.  The amount of code
you have to link in when you choose sprintf is quite large, however.  The
supplied string functions allow you to easily format and parse string data
without linking a large chunk of code.

It is suggested that you link the StringUtils executable into the code segment
that contains main().  This will guarantee that the string functions are always
resident in memory when you call them.  If the code isn't in ram when you make
a string call, the loading of the code may cause memory to move or compress.
This is fine, unless you passed a pointer into an unlocked handle as a string
pointer.  If you point into an unlocked handle, simply calling the function can
move memory, unless it is guaranteed that the code is already in memory.  By
linking it into the same code segment as main(), you guarantee that it is
always in memory.  (All of the sample applications already do this.)

For Think C users, DTS.Lib..utils.π contains the following source files:
    AppleTalk.c
    GWLayers.c
    ListControl.c
    PPC.c
    TextEditControl.c
    Utilities.c

Again, if you are using MPW, all of the files are linked into a single library
called DTS.Lib.  The StringUtils code #pragma segment compiler option declares
the code segment to be StringUtils.  The make files for the applications
redirect StringUtils code to be placed in the Main segment, so you are guaranteed
to have the StringUtils code always available in ram.


The above code can be used without committing to the entire DTS.Lib application
framework.  You can write your own application completely from scratch and then
call any of the code in the above-mentioned files anytime you want.

Each of the above files has useful stand-alone code you will probably want to
look at, even if you choose not to use the DTS.Lib application framework.

If you choose to use the DTS.Lib application framework, (from now on called
DTS.framework), very much of the application development tasks are already done
for you.

DTS.framework currently supports:
    Multiple windows
    Multiple document types
    File I/O
    Apple Events
    Window/document scrolling
    Hierarchical document architecture
    Infinite undo (undos can optionally be saved with the document)
    Floating palettes
    Viewing window for displaying document objects
    Other document-specific tasks, such as mouseDowns, keyDowns, cursors, etc.

What tasks DTS.framework doesn't directly supply can probably be found in the
DTS utilities, so between the two, many of the aspects of Mac application
development are already complete.


So what is the minimum you have to know to get started?

Above, we discussed the various components of the DTS library code.  So now we
need to know the easiest way to use this code.  The easiest way is to make a
copy of the sample application Zippo, and start adding code.  Consider Zippo
an application shell which already correctly uses the DTS.framework and
utilities.  All that is missing is the code that is specific to your
application.  Everything that is generic is already in there.

The best place to start explaining is how to manage documents.  We will start
with a code snippet from Zippo:

switch (menuItem) {
    case iNew:
        err = NewDocument(&frHndl, docFileType, true);
        if (!err) {
            err = DoNewWindow(frHndl, nil, FrontWindow(),
                              (WindowPtr)-1, kwAppWindow);
            if (err) DisposeDocument(frHndl);
        }
        if (err) CenteredAlert(rErrorAlert, nil, (ModalFilterProcPtr)AlertFilter);
        break;
    case iOpen:
        .
        .
        .


This is right out of the file menu.c  We get to this code by the user choosing
"New" from the file menu.  The first thing we do is to try to create the new
document.  This is done with the DTS.framework call NewDocument().

All NewDocument() does, if successful, is to create a handle to the size of the
document structure, and initialize many of the fields.  If it succeeds, frHndl
is set to that handle.  If it fails, frHndl is set to nil, and the reason for
the failure is returned into err.

As stated above, DTS.framework can support multiple document types.  The type
of the document we are trying to create is docFileType, which is an OSType.
In Zippo, docFileType is defined as follows:
    #define docFileType      'DUMD'

'DUMD' stands for dumb document.  I consider it dumb because when the document
is saved, it is saved with no content.  The DTS.framework very carefully saves
nothing.  You can then open nothing later.  You can print nothing, etc.
Hopefully, you will remedy this situation.

The third parameter to NewDocument() tells NewDocument() that you want to
create a document with a new "Untitled #" style of window title.  The true
indicates to DTS.framework that you want this document to have an untitled
number one greater then the last time that NewDocument() was called.  No big
deal, but I figured you would curious at this point.

If NewDocument() succeeds, you now have a new document that has no window.
Once the document is successfully create, you then want to give the document
a window.  This is done with the DoNewWindow() call.  You pass in the frHndl
that NewDocument() created.

The prototype for DoNewWindow is:

OSErr    DoNewWindow(FileRecHndl frHndl, WindowPtr *retWindow,
                    WindowPtr relatedWindow, WindowPtr behind, short attributes)

If DoNewWindow() successfully creates a window, the window is returned in
retWindow, if retWindow is not nil.  Many times you don't really care what the
window that was created is.  In this case, if it is successful, it is now the
new top window.  If the user clicks on it, then you care.  Here you don't.

If DoNewWindow() was unsuccessful at creating the window, you now are left with
a document, frHndl, that has no window.  If this occurs, you want to dispose of
the document, and report an error.

That's all there is to it.  Oh, the remaining parameters to DoNewWindow():
    relatedWindow:    Create the window on the same monitor that holds most of
                    this window. If nil is passed in, create the window on the
                    main monitor.
    behind:            Create the window behind the window indicated.
                    -1 puts it on top.
    attributes:        Various window attributes can be indicated here.  They are:

        #define kwGrowIcon            1
        #define kwHScroll            2
        #define kwHScrollLessGrow    6
        #define kwVScroll            8
        #define kwVScrollLessGrow    24
        #define kwVisible            32
        #define kwOpenAtOldLoc        64
        #define kwDoFirstClick        128
        #define kwIsDocument        0
        #define kwIsPalette            256
        #define kwIsModalDialog        512

So, if you want to create a window with document scrollbars, you just set a few
bits in the attribute field, and you're done.  And yes, kwOpenAtOldLoc
automatically opens the window wherever the user had it when it was closed,
and yes it makes sure that it is at least partially visible on some monitor.
You can find more information elsewhere.


Now that we understand document creation and window creation using
DTS.framework, here's the rest of the story:


As mentioned above, NewDocument() returns a handle.  This handle is your
reference to the document, thus my favorite variable name for one os these
things:  frHndl (file reference handle).  You don't have to worry about
associating the frHndl with the window that was created for it.  DoNewWindow()
stores the frHndl in the window's refcon field.  Also, you don't have to worry
about which window belongs to a particular frHndl, as the window is stored in
the frHndl, as well.  The document and its associated window both point to one
another.  (You got one, you got the other -- cool.)


Basically, everything that goes on with document goes on inside the frHndl.
The frHndl is a handle that holds the structure for the document.  Most of this
structure looks like this:

typedef struct {
    OSType                        sfType;
    Boolean                        defaultDoc;
    Movie                        movie;
    short                        movieResID;
    short                        movieFlags;
    Boolean                        movieDataRefWasChanged;
    Boolean                        docDirty;
    long                        modNum;
    long                        modTick;
    Boolean                        readOnly;
    short                        refNum;
    short                        resRefNum;
    FSSpec                        fss;
    short                        windowID;
    WindowPtr                    window;
    GetDocWindowProcPtr            getDocWindow;
    CalcFrameRgnProcPtr            calcFrameRgnProc;
    ContentClickProcPtr            contentClickProc;
    ContentKeyProcPtr            contentKeyProc;
    DrawFrameProcPtr            drawFrameProc;
    FreeDocumentProcPtr            freeDocumentProc;
    FreeWindowProcPtr            freeWindowProc;
    ImageProcPtr                imageProc;
    InitContentProcPtr            initContentProc;
    ReadDocumentProcPtr            readDocumentProc;
    ReadDocumentHeaderProcPtr    readDocumentHeaderProc;
    ResizeContentProcPtr        resizeContentProc;
    ScrollFrameProcPtr            scrollFrameProc;
    UndoFixupProcPtr            undoFixupProc;
    WindowCursorProcPtr            windowCursorProc;
    WriteDocumentProcPtr        writeDocumentProc;
    WriteDocumentHeaderProcPtr    writeDocumentHeaderProc;
    short                        attributes;
    Rect                        windowSizeBounds;
    ControlHandle                hScroll;
    ControlHandle                vScroll;
    short                        hScrollIndent;
    short                        vScrollIndent;
    short                        leftSidebar;
    short                        topSidebar;
    short                        hArrowVal;
    short                        vArrowVal;
    short                        hPageVal;
    short                        vPageVal;
} FileStateRec;


Here's some explanation of some of the fields:

sfType:                    The type of the document you passed to NewDocument() is
                        stored here.

defaultDoc:                Used by application framework to determine if View Hierarchy
                        facility can be used to view the document.

movie:                    These 4 fields are used together.  If the document type used
movieResID:                is of type 'MooV' for either NewDocument or OpenDocument,
movieFlags:                then these fields are used to keep track of the movie information
movieDataRefWasChanged:    for the document.  In addition to this information, the meaning of
                        the field refNum is extended somewhat.  Here's the deal:
                        Movie files are generally resource-fork-based, but this isn't
                        always the case.  The movie file can be flattened and made to
                        be data-fork-based.  This is so MS-DOS machines can handle the
                        movie file.
                        To be consistent with regular document files, the resRefNum
                        returned by OpenMovieFile (which isn't always a resource refNum)
                        is kept in the field refNum.  Normally refNum represents a data
                        fork, but in the case of movies, it may be either a data fork or
                        resource fork reference number.
                        For regular documents, if you wish to use the resource fork, you
                        use the calls UseDocResFile and CloseDocResFile.  These still work
                        for movies, whether the movie is data-fork- or resource-fork-based.
                        If the movie is resource fork based, then UseDocResFile simply
                        copies the refNum field into the resRefNum field.  This is the
                        correct thing to do, as the resource is already opened for the movie.
                        CloseDocResFile looks at the refNum and resRefNum fields.  If they
                        are the same, then it simply sets resRefNum to kInvalidRefNum.
                        This is all that is necessary to "close" the resource fork, as you
                        really don't want it to close, since it was opened for the movie.
                        All of this behavior is simply to allow the various calls to do the
                        appropriate thing when the document is a movie.  You should be able
                        to handle movie files just like regular document files.

docDirty:                Used by the application framework to determine if a
                        "Save before closing" dialog should be displayed.

modNum:                    This is incremented whenever you call SetDocDirty().  Some
                        applications find this information useful.  Most don't care.

modTick:                Tick count of last modification.  (See modNum).

readOnly:                True if document is opened read-only.  DTS.framework sets
                        this if the document that is selected by the user can't be
                        openeded with read-write access.  DTS.framework asks the
                        user if it is okay to open it read-only.

refNum:                    The file reference number (0 if it is a new document.)

resRefNum:                Reference number of the resource fork of the document file.
                        Unless you specifically use the resource fork, the
                        document's resource fork isn't opened.

FSSpec                    The FSSpec for the open file (if there is one open for this
                        document.)

windowID:                The resource ID of the 'WIND' resource to be used when
                        DoNewDocument() is called to give this document a window.
                        windowID is initialized to rWindow, which is defined to be
                        128.  If you want a different 'WIND' resource for this
                        document, set this field after calling NewDocument(), and
                        prior to calling DoNewWindow().

window:                    When you call DoNewWindow(), if it succeeds at creating a
                        window, it places the window pointer here.

The next fields are the procedure pointers that determine the behavior of the
document.  These fields are initialized to point to the following functions:

getDocWindow:                GetStaggeredWindow;
calcFrameRgnProc:            CalcFrameRgn;
contentClickProc:            ContentClick;
contentKeyProc:                ContentKey;
drawFrameProc:                DrawFrame;
freeDocumentProc:            FreeDocument;
freeWindowProc:                FreeWindow;
imageProc:                    ImageDocument;
initContentProc:            InitContent;
readDocumentProc:            ReadDocument;
readDocumentHeaderProc:        DefaultReadDocumentHeader;
resizeContentProc:            ResizeContent;
scrollFrameProc:            ScrollFrame;
undoFixupProc:                UndoFixup;
windowCursorProc:            WindowCursor;
writeDocumentProc:            WriteDocument;
writeDocumentHeaderProc:    DefaultWriteDocumentHeader;

With the exception of the function GetStaggeredWindow, all of the above
functions are part of the application shell Zippo.  GetStaggeredWindow is a
function in the DTS utilities that opens a window "staggered" from existing
windows.  This allows some of the window to be exposed so that the user can
easily click on the window and bring it to the front.

All of the other functions are part of your application.  They get called by
the application framework at appropriate times.  They don't get called at some
magic moment.  They get called when your application calls DTS.framework to do
something.  DTS.framework does the generic work. The application-specific work
it can't do, and so it calls your application to do that part.

Even for something as supposedly application-specific as drawing the window
content, you still will call DTS.framework to get the job started.  You will
call the function DoImageDocument().  You pass DoImageDocument() a file
reference handle (frHndl).  DoImageDocument() dereferences the frHndl and
gets the value at the field imageProc.  If imageProc is nil, then there is
no imaging procedure for this document, and DoImageDocument() just returns.
If there is a procedure pointer stored in the field imageProc, then that
code is called.

There is no particular magic happening here.  The DoImageDocument() code looks
just as you would expect:

OSErr    DoImageDocument(FileRecHndl frHndl)
{
    ImageProcPtr    proc;
    OSErr            err;

    err = noErr;
    if (proc = (*frHndl)->fileState.imageProc) err = (*proc)(frHndl);
    return(err);
}

If there is an imaging procedure in the file reference, call it.  Otherwise
it just returns noErr.

Initially imageProc has a value.  The initial value is ImageDocument.  The
ImageDocument() function is located in the Zippo file Window2.c.  If your
application only has a single document type, then just place your document
imaging code inside the stub function ImageDocument().  It's that easy.

For the most part, all of the procedure pointers in the frHndl have a "Do"
function.  For example:  If you want to draw the "frame" portion of a window,
you wouldn't call DrawFrame().  You would call DoDrawFrame().  DoDrawFrame()
will look up the procedure pointer, and if it is not nil, it will call it,
just like DoImageDocument() does.


So how exactly does a file reference handle get created?  Again, nothing
magic, but there are a number of steps that need to be understood.


The creation of an frHndl is invoked by the application.  The application
calls either NewDocument() or OpenDocument(), discussed above.  OpenDocument()
calls NewDocument(), so in either case, you are actually calling NewDocument().

I think the easiest way to explain what NewDocument() does is to show the code.
The explanation follows.  Here's the code:


OSErr    NewDocument(FileRecHndl *returnHndl, OSType sftype, Boolean incTitleNum)
{
    long            size;
    FileRecHndl        frHndl;
    FileRecPtr        frPtr;
    Str255            untitled;
    StringPtr        pstr;
    OSErr            err;
    short            i;
    static short    untitledCount;

    err  = memFullErr;                /* Assume that we will fail. */

    size = InitDocumentSize(sftype);
        /* Call the application and ask it how big the frHndl should be for
        ** this document type.  We can't know, so we'll ask. */

    if (*returnHndl = frHndl = (FileRecHndl)NewHandleClear(size)) {
        /* Create (or try to) the frHndl, initialized to all 0's */

        for (i = gTypeListLen; --i;) if (sftype == gTypeList[i]) break;
            /* Walk the typeList to find this file type.  We are interested in
            ** where we find the entry.  The position we find it is used as a
            ** string number into the rDefaultTitles STR# resource.  We get
            ** an individual string from this location.  This allows us to
            ** have different default titles for different document types. */

        for (++i; i; i--) {
            GetIndString(untitled, rDefaultTitles, i);
            if (untitled[0]) break;  /* Quit if we succeeded at getting one. */
        }
        frPtr = *frHndl;
        frPtr->fileState.sfType                  = sftype;
        frPtr->fileState.modNum                  = GetModNum();
        frPtr->fileState.modTick                 = TickCount();
        frPtr->fileState.refNum                  = kInvalRefNum;
        frPtr->fileState.resRefNum               = kInvalRefNum;
        frPtr->fileState.fss.vRefNum             = kInvalVRefNum;
        frPtr->fileState.windowID                = rWindow;
            /* The above sets the fileState constants for the document.  Note
            ** that we use a default 'WIND' ID for the expected window resource.
            ** This can be changed later, if the default isn't good enough. */

        frPtr->fileState.getDocWindow            = GetStaggeredWindow;
        frPtr->fileState.calcFrameRgnProc        = CalcFrameRgn;
        frPtr->fileState.contentClickProc        = ContentClick;
        frPtr->fileState.contentKeyProc          = ContentKey;
        frPtr->fileState.drawFrameProc           = DrawFrame;
        frPtr->fileState.freeDocumentProc        = FreeDocument;
        frPtr->fileState.freeWindowProc          = FreeWindow;
        frPtr->fileState.imageProc               = ImageDocument;
        frPtr->fileState.initContentProc         = InitContent;
        frPtr->fileState.readDocumentProc        = ReadDocument;
        frPtr->fileState.readDocumentHeaderProc  = DefaultReadDocumentHeader;
        frPtr->fileState.resizeContentProc       = ResizeContent;
        frPtr->fileState.scrollFrameProc         = ScrollFrame;
        frPtr->fileState.undoFixupProc           = UndoFixup;
        frPtr->fileState.windowCursorProc        = WindowCursor;
        frPtr->fileState.writeDocumentProc       = WriteDocument;
        frPtr->fileState.writeDocumentHeaderProc = DefaultWriteDocumentHeader;
            /* Initialize all of the procedure pointers to default values.
            ** If the defaults aren't any good, they will be changed later. */

        pstr = frPtr->fileState.fss.name;
        pcpy(pstr, untitled);
        if (incTitleNum) ++untitledCount;
        pcatdec(pstr, untitledCount);
            /* Create the default document title.  It is stored in the FSSpec,
            ** as we can't place it in the window title.  We don't have a window
            ** yet to "title".  This will happen later.  The title is gotten
            ** from the FSSpec, so we are effectively done. */

        err = InitDocument(frHndl);
            /* Call the application for any additional document initialization.
            ** Other handles may need to be allocated.  The default values
            ** above may be incorrect for a certain document type.  This gives
            ** the application a chance to change any defaults that
            ** are incorrect. */

        if (err) {
            DisposeHandle((Handle)frHndl);
            *returnHndl = nil;
                /* If the application couldn't complete the document
                ** initialization, pitch the handle. */
        }
    }

    return(err);
}



Above is the entire NewDocument() function.  There are two key points to note:

1) The call to InitDocumentSize()
2) The call to InitDocument()

These two functions are part of your application.  (They are in the source file
file2.c)  The first is called just so NewDocument() knows how big a handle to
create for the document reference.  If your application has only one document
type, then this function will simply return a constant.  If your application
has multiple document types, you will want to return the size that corresponds
to the document type (OSType).

Your application's function InitDocumentSize() is passed the OSType.  At this
point, this is the only piece of information we have on the document-to-be.
Until the application framework knows the size, it can't create the file
reference handle.  You tell the application framework how big to create the
frHndl.  It creates it to the requested size, and initializes it to 0's and
default values.

Once it is initialized to defaults, NewDocument() calls your application, giving
it a chance to change the default values.  Only the frHndl is passed to
InitDocument().  The frHndl from this point on is the document reference.

If you have different document types, you will have to have a reasonably smart
InitDocument() function.  It will have to look at the document type, and then
adjust the default values for the frHndl based on the document type.  At this
point, the document type is stored in the frHndl, in the field fileState.sfType.

All of this is done prior to a window being created for the frHndl.  This is
important, as a number of the procedure pointers determine how the window will
be created.  You need to make customizations to the frHndl after its creation,
and prior to the creation of the document's window.

Of course, if your application only has one document type, then these defaults
are just fine, and you won't have to worry about all of this stuff.


Let's revisit the code for a "New" menu item choice:


err = NewDocument(&frHndl, docFileType, true);
if (!err) {
    err = DoNewWindow(frHndl, nil, FrontWindow(), (WindowPtr)-1, kwAppWindow);
    if (err) DisposeDocument(frHndl);
}
if (err) CenteredAlert(rErrorAlert, nil, (ModalFilterProcPtr)AlertFilter);


We have explored what happens when NewDocument() is called.  All that remains
is the DoNewWindow() call.


A window is opened for the frHndl.  The values stored in the frHndl are used
to determine how to open the window.

In the sample call above, we create a window for the document frHndl.  Here's
what the parameters indicate:

nil:            Don't bother returning a reference to the window created.
                If we cared, we might pass in something like &newWindow.
FrontWindow():    Window is created on the same monitor that holds most of the
                current front window.
(WindowPtr)-1:    Window is created as the front-most window.
kwAppWindow:    Window is created with these attributes (described above).


That's all there is to it.  Now all you need is a way to hold your document
data.


Interestingly enough, DTS.framework has plenty of document support.  You can
use the hierarchical document architecture built into DTS.framework.  It is
very powerful.  It handles file I/O, hierarchically related data, infinite
undo, etc.


The hierarchical document architecture is the default type of document.  If
you choose to use it, there are already calls supplied to create the initial
default document.  All you have to do is to call DefaultInitDocument() in
your application's InitDocument() function.  For all documents that use the
hierarchical document architecture, simply call DefaultInitDocument() from
within InitDocument().

What DefaultInitDocument does is it creates a root object of type TreeObjHndl
and places it in an expected location within the frHndl for the document.
Consider this as a document within a document.  The frHndl describes the
run-time aspects of the document.  The root object in the hierarchy begins
the portion of the document that "persists", that is, saves to disk.

The root object is just that.  Yes, it has a data portion to it, but the main
purpose of the root object is a holder of the "child" objects of the document.

Whenever you make a change to the document, you will make it to some number of
objects with the hierarchy.  There are specific calls for this, and if you stick
to these calls, infinite undo works automatically.  There is a separate document
describing the hierarchical document architecture.  You will find it in the
DTS.Lib folder.  It is called "=Using TreeObj.c".  It will detail everything
you need to know about using the hierarchical document package.

Let's review the chain of information for a document, startiong with the window:

window:        References the document (frHndl) associated with the window.
            The reference to the frHndl is kept in the window's refcon field.

frHndl:        References back to the window.  This means that if you have either
            the window or the frHndl for a document, you can easily get the
            other.

            Also references the root hierarchy object.  This is true only if you
            elect to use the TreeObj package in the DTS.framework.  DTS.Draw
            uses this package.  MacShell does not.


root:        References the frHndl that contains it.

            Also references the undo root object that contains all of the
            information necessary to undo/redo edits to the document.

            References all of the children added to the root object.


child:        References all child it may in turn have.

            References the parent object.  The root object can also be
            considered a child, but it is a child with no parent.  This
            is reflected in the parent reference.  If the parent reference
            is nil, then the object is a root object.


This is a nice top-down view of where document/window information is stored.
Here's some more information:

frHndl information is NOT saved with the document.  Any information you wish
to be saved with the document must be contained in a hierarchy object.

Changes to the root object can't be undone.  The location in the document
that is automatically kept for undo/redo operations is referenced by parent
and child number.  This locates you to any object within the hierarchy,
except for one.  The root object has no parent, so the location of the root
object can not be indicated by parent/childNum.

This means:

• Any information tht is run-time, and you DON'T want saved to disk should be
  kept directly in the frHndl.
• Any information that you want to keep with the document, but you don't want
  involved in undo/redo operations should be kept in the root object.
• Any information that you want to be able to save and undo/redo in the
  document should be kept in a child below the level of the root object.


Of course, all of the rules from the root object down imply that you are using
the hierarchical document architecture.  This is a completely optional package.
All other rules continue to apply, whether or not you are using this package.




With the exception of the root object, all of the above information is kept it
the fileState portion of an frHndl.  The root object begins the actual document,
so it is actually in the document portion of an frHndl.  Why am I talking about
frHndl portions?  Because an frHndl is comprised of three distinct structures.
They are:

FileStateRec:    This is most adequately covered above.
ConnectRec:        This hasn't even been mentioned.
TheDoc:            This has been hinted at.


The ConnectRec portion of a document record looks like this:

typedef struct {
    long            windowID[2];        /* Used to match up windows. */
    short            endSendInfo;        /* Above is send info.         */

    Boolean            connected;            /* Flag showing we are connected.      */
    AEAddressDesc    remoteLoc;            /* AppleEvent address of remote user. */
    Str32            remoteName;            /* Name of user connected to.          */
    Str32            remoteZone;            /* Zone of user connected to.          */
    Str32            remoteMachine;        /* Machine name of user connected to. */
    short            endLocalInfo;        /* Above info is for 1 machine only.  */
} ConnectRec;

The ConnectRec is used by DTS.framework to establish a connection to
another application (or itself).  This connection links two specific windows.
Once connected, the boolean 'connected' is set true, and the other fields
are filled in.  The AEAddressDesc of whom you connected to is saved.  The name,
zone, and machine name are also kept.  The endLocalInfo field is a reference
point to determine the end of the ConnectRec at run-time.  This is here in case
there are additional fields added in the future.  They would be added before the
endLocalInfo field.  Since the ConnectRec structure is DTS.framework's
responsibility to maintain, you don't have to worry about this.  (I do.)


To see how to use the Apple Event facilities of DTS.framework, check out the
application MacShell.  It uses these facilities.



The final component of an frHndl is the document portion.  It looks like this:


typedef struct {
    DocHeaderInfo    fhInfo;  /* Doc hdr info (vers, prRec, window loc.) */
    TreeObjHndl        root;
} TheDoc;


where DocHeaderInfo looks like this:


typedef struct {
    short        version;            /* The file format version.                 */
    Boolean        printRecValid;        /* True if prRec has been created.         */
    TPrint        print;                /* Print record for file.                 */
    Rect        structureRect;        /* Remember where window was when saved. */
    Rect        contentRect;        /* Remember where window was when saved. */
    Rect        stdState;            /* This and below rect used for saving     */
    Rect        userState;            /* zoom information for window.             */
    long        hDocSize;            /* hDocSize and vDocSize have to be      */
    long        vDocSize;            /* saved with the document /* so that     */
                                    /* the window can be created the         */
                                    /* correct size.                         */
    short        endDocHeaderInfo;    /* End version, print, and window info.     */
} DocHeaderInfo;


I suppose you figured that the document portion was your domain.  Well, it is,
kind of.  Since DTS.framework supplies hierarchical document support, it has
to have access to this portion of the frHndl, as well.  You always need the
fhInfo field of the document portion.  Also, it must be the first field in
the structure.

You optionally need the root field.  If you are using the hierarchical document
package, then you must have this field, and it must be the second field.

Aside from these two rules, the structure is all yours.  You can add as much as
you wish to it.


As has been described above, a single frHndl consists of three components.
These are:
    1) FileStateRec
    2) ConnectRec
    3) The document record.

The way you assemble these parts into a single frHndl is like this:


typedef struct FileRec {
    FileStateRec    fileState;        /* DTS.Lib expects this structure here. */
    ConnectRec        connect;        /* DTS.Lib expects this structure here. */
    union {
        TheDoc    doc;                /* Union in each document type here. */
    } d;
} FileRec;


This combines the three documents parts into a single structure.  Note the use
of union for the actual document portion.  This is because you can have multiple
document types within your application.  Whenever you add a document type, just
create a structure for it, and then union in this new structure into the FileRec
definition.  That's all there is to it (sort of).

You have to remember to change the InitDocumentSize() and InitDocument()
functions so that they can handle the new document type.  Once this is done,
you now have a new document type added to your application.


I think this should give you a good feel of what you need to first, second, etc.
Any other questions about using DTS.Lib and Zippo should be answered in other
read.me files.  Of course, you can always look at the sample applications
DTS.Draw and MacShell for implementation-specific details.


Eric Soldan